home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 for Intel / NeXTSTEP 3.2 for Intel.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbconvert.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  7.0 KB  |  210 lines
  1. .Na "dbconvert" 
  2. .Aa
  3. .Fu
  4. Convert data from one datatype to another.
  5. .Ih "datatype conversion"
  6. .Sy
  7. .Sf "DBINT dbconvert(dbproc, srctype, src, srclen, desttype, dest, destlen)"
  8. .Sp "DBPROCESS" "*dbproc"
  9. .Sp "int" "srctype"
  10. .Sp "BYTE" "*src"
  11. .Sp "DBINT" "srclen"
  12. .Sp "int" "desttype"
  13. .Sp "BYTE" "*dest"
  14. .Sp "DBINT" "destlen"
  15. .Co
  16. .Bl
  17. This routine allows the program to convert data from one
  18. representation to another.
  19. To determine whether a particular conversion is permitted,
  20. the program can call \f2dbwillconvert()\f1 before attempting a conversion.
  21. .Bl
  22. \f2dbconvert()\f1 can convert data stored in
  23. any of the \*S datatypes (although, of course,
  24. not all conversions are legal):
  25. .sp
  26. .nf
  27. .in +5n
  28. .ta +25n
  29. .ne 12.5v
  30. \f3\*S type    Program variable type\f1
  31. .sp 0.5v
  32. SYBCHAR    DBCHAR
  33. .mc |
  34. SYBTEXT    DBCHAR
  35. .mc
  36. SYBBINARY    DBBINARY
  37. .mc |
  38. SYBIMAGE    DBBINARY
  39. .mc
  40. SYBINT1    DBTINYINT
  41. SYBINT2    DBSMALLINT
  42. SYBINT4    DBINT
  43. SYBFLT8    DBFLT8
  44. SYBBIT    DBBIT
  45. SYBMONEY    DBMONEY
  46. SYBDATETIME    DBDATETIME
  47. .fi
  48. .in -5n
  49. .sp 0.5v
  50. .Bl
  51. The table below lists the datatype conversions that
  52. \f2dbconvert()\f1 supports.
  53. The source datatypes are listed down the leftmost column and
  54. the destination datatypes are listed along the top row of the table.
  55. (For brevity, the prefix ``SYB'' has been eliminated from
  56. each datatype.)
  57. T (TRUE) indicates that the conversion is
  58. supported; F (FALSE) indicates that the conversion is not supported.
  59. .Ih "datatype conversion, supported"
  60. .sp
  61. .nf
  62. .in +3n
  63. .ps -4
  64. .vs -4
  65. .ta +17n +10n +10n +10n +10n +10n +10n +10n +10n +7n +13n
  66. .ne 17.5v
  67. \f3FROM:    TO:\f1
  68. .sp 0.5v
  69. .mc |
  70. \f3            BIN-                                DATE-
  71.     CHAR    TEXT    ARY    IMAGE    INT1    INT2    INT4    FLT8    BIT    MONEY    TIME\f1
  72. .ta +19n +10n +10n +10n +10n +10n +10n +10n +9n +10n +11n
  73. .sp 0.5v
  74. \f3CHAR\f1    T    T    T    T    T    T    T    T    T    T    T
  75. .sp 0.25v
  76. \f3TEXT\f1    T    T    T    T    T    T    T    T    T    T    T
  77. .sp 0.25v
  78. \f3BINARY\f1    T    T    T    T    T    T    T    T    T    T    F
  79. .sp 0.25v
  80. \f3IMAGE\f1    T    T    T    T    T    T    T    T    T    T    F
  81. .sp 0.25v
  82. \f3INT1\f1    T    T    T    T    T    T    T    T    T    T    F
  83. .sp 0.25v
  84. \f3INT2\f1    T    T    T    T    T    T    T    T    T    T    F
  85. .sp 0.25v
  86. \f3INT4\f1    T    T    T    T    T    T    T    T    T    T    F
  87. .sp 0.25v
  88. \f3FLT8\f1    T    T    T    T    T    T    T    T    T    T    F
  89. .sp 0.25v
  90. \f3BIT\f1    T    T    T    T    T    T    T    T    T    F    F
  91. .sp 0.25v
  92. \f3MONEY\f1    T    T    T    T    T    T    T    T    T    T    F
  93. .sp 0.25v
  94. \f3DATETIME\f1    T    T    T    T    F    F    F    F    F    F    T
  95. .fi
  96. .ps +4
  97. .vs +4
  98. .sp 0.5v
  99. .mc
  100. .in -3n
  101. .Bl
  102. A conversion to or from the datatypes SYBBINARY and SYBIMAGE
  103. is a straight bit-copy, except when the conversion involves
  104. SYBCHAR or SYBTEXT.
  105. When converting SYBCHAR or SYBTEXT data to SYBBINARY or SYBIMAGE, \f2dbconvert()\f1
  106. interprets the SYBCHAR or SYBTEXT string as hexadecimal, whether or
  107. not the string contains a leading ``0x''.
  108. When converting SYBBINARY or SYBIMAGE data to SYBCHAR or SYBTEXT, \f2dbconvert()\f1
  109. creates a hexadecimal string without a leading ``0x''.
  110. .Bl
  111. Converting a SYBMONEY, SYBCHAR, or SYBTEXT value to SYBFLT8 may result in some loss of precision.
  112. Converting a SYBFLT8 value to SYBCHAR or SYBTEXT may also result in some loss of precision.
  113. .Bl
  114. Converting a SYBFLT8 value to SYBMONEY can result in overflow, because the maximum value for 
  115. SYBMONEY is $922,337,203,685,477.58.
  116. .Bl
  117. If overflow occurs when converting integer or float data to SYBCHAR or SYBTEXT,
  118. the first character of the resulting value will contain an asterisk (``*'') to indicate the error.
  119. .Bl
  120. A conversion to SYBBIT has the following effect:
  121. If the value being converted is not 0, the SYBBIT value will be set to 1; if the value \f2is\f1 0,
  122. the SYBBIT value will be set to 0.
  123. .Bl
  124. In certain cases, it can be useful to convert a datatype to itself.
  125. For instance, a conversion of SYBCHAR to SYBCHAR with a \f2destlen\f1 of -1 serves as
  126. a useful way to append a null terminator to a string, as the example below illustrates.
  127. .Bl
  128. Here's a short example that illustrates how to convert \*S data obtained with \f2dbdata()\f1:
  129. .ta +4n +4n +4n +4n +4n +4n
  130. .SD
  131. .so dbconvert.ex
  132. .ED
  133. In the \f2dbconvert()\f1 calls it was not necessary to cast the returns from \f2dbdata()\f1, because
  134. \f2dbdata()\f1 returns a BYTE pointer\(emprecisely the datatype
  135. \f2dbconvert()\f1 expects in the third parameter.
  136. .Bl
  137. If you're binding data to variables with \f2dbbind()\f1 rather than accessing the data directly
  138. with \f2dbdata()\f1, 
  139. \f2dbbind()\f1 can perform the conversions itself, making \f2dbconvert()\f1 unnecessary.
  140. .Bl
  141. Example 5 in the \f2\*L Reference Supplement\f1 illustrates several more types of conversions using \f2dbconvert()\f1.
  142. .Bl
  143. For more information on \*S datatypes, see the \f2Commands Reference\f1 and the \f2types\f1 manual
  144. page in this document.
  145. .Bz
  146. .Pa
  147. .Pi dbproc
  148. A pointer to the DBPROCESS structure that provides the connection
  149. for a particular front-end/\*S process.  It contains all the
  150. information that \*L uses to manage communications and data between the
  151. front end and \*S.
  152. In \f2dbconvert()\f1, the DBPROCESS is used only to supply any custom null
  153. values that the program may have specified via \f2dbsetnull()\f1.
  154. If \f2dbproc\f1 is NULL, \f2dbconvert()\f1 uses the default values
  155. for null value data conversions.
  156. .Pi srctype
  157. The datatype of the data which is to be converted.
  158. This parameter can be any of the \*S datatypes,
  159. as listed in the first table above.
  160. .Pi src
  161. A pointer to the data which is to be converted.
  162. If this pointer is NULL, \f2dbconvert()\f1 will place an appropriate
  163. null value in the destination variable.
  164. You can use \f2dbdata()\f1 to get the \*S data.
  165. .Pi srclen
  166. The length, in bytes, of the data to be converted.
  167. If the \f2srclen\f1 is 0, the source data is assumed to be null
  168. and \f2dbconvert()\f1 will place an appropriate null value
  169. in the destination variable.
  170. Otherwise,
  171. this length is ignored for all datatypes except character, text, binary, and image.
  172. For SYBCHAR data, a length of -1 indicates that the string is null-terminated.
  173. You can use \f2dbdatlen()\f1 to get the length of \*S data.
  174. .Pi desttype
  175. The datatype that the source data is to be converted into.
  176. This parameter can be any of the \*S datatypes,
  177. as listed in the first table above.
  178. .Pi dest
  179. A pointer to the destination variable that will receive the converted data.
  180. If this pointer is NULL, \f2dbconvert()\f1 will call the user-supplied error
  181. handler (if any) and return FAIL.
  182. .Pi destlen
  183. The length, in bytes, of the destination variable.
  184. \f2destlen\f1 is ignored for fixed-length datatypes.
  185. For a SYBCHAR destination, the value of \f2destlen\f1 must be the total length
  186. of the destination buffer space.
  187. A length of -1 for a SYBCHAR or SYBBINARY destination
  188. means that there is sufficient space available.
  189. In addition, for a SYBCHAR destination a length of -1 will cause the character string
  190. to be given a terminating null.
  191. .in -.375i
  192. .Re
  193. .br
  194. The length of the converted data, in bytes, if the datatype conversion succeeds.
  195. If the conversion fails, \f2dbconvert()\f1 returns -1.
  196. If \f2dbconvert()\f1 fails, it will first call a user-supplied error handler (if any)
  197. and set the global \*L error value.
  198. .sp
  199. This routine may fail for several reasons: the requested conversion was not available;
  200. the conversion resulted in truncation, overflow, or loss of precision in the destination
  201. variable; or a syntax error occurred in converting a character string to some numeric type.
  202. .Sa
  203. dbaltbind,
  204. dbbind,
  205. dberrhandle,
  206. dbsetnull,
  207. dbwillconvert,
  208. errors,
  209. types
  210.